'\" te
.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH DDI_REMOVING_POWER 9F "Mar 14, 2001"
.SH NAME
ddi_removing_power \- check whether \fBDDI_SUSPEND\fR might result in power
being removed from a device
.SH SYNOPSIS
.nf
#include <sys/ddi.h>
#include <sys/sunddi.h>



\fBint\fR \fBddi_removing_power\fR(\fBdev_info_t\fR \fI*dip\fR);
.fi

.SH INTERFACE LEVEL
illumos DDI specific (illumos DDI)
.SH DESCRIPTION
The \fBddi_removing_power()\fR function indicates whether a currently pending
call into a driver's \fBdetach\fR(9E) entry point with a command of
\fBDDI_SUSPEND\fR is likely to result in power being removed from the device.
.sp
.LP
\fBddi_removing_power()\fR can return true and power still not be removed from
the device due to a failure to suspend and power off the system.
.SH PARAMETERS
The \fBddi_removing_power()\fR function supports the following parameter:
.sp
.ne 2
.na
\fB\fIdip\fR\fR
.ad
.RS 7n
pointer to the device's \fBdev_info\fR structure
.RE

.SH RETURN VALUES
The \fBddi_removing_power()\fR function returns:
.sp
.ne 2
.na
\fB\fB1\fR\fR
.ad
.RS 5n
Power might be removed by the framework as a result of the pending
\fBDDI_SUSPEND\fR call.
.RE

.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 5n
Power will not be removed by the framework as a result of the pending
\fBDDI_SUSPEND\fR call.
.RE

.SH EXAMPLES
\fBExample 1 \fRProtecting a Tape from Abrupt Power Removal
.sp
.LP
A tape driver that has hardware that would damage the tape if power is removed
might include this code in its \fBdetach\fR(9E) code:

.sp
.in +2
.nf
int
     xxdetach(dev_info_t *dip, ddi_detach_cmd_t cmd)
     {

     ...
          case DDI_SUSPEND:
          /*
           * We do not allow DDI_SUSPEND if power will be removed and
           * we have a device that damages tape when power is removed
           * We do support DDI_SUSPEND for Device Reconfiguration,
           * however.
           */
             if (ddi_removing_power(dip) && xxdamages_tape(dip))
                return (DDI_FAILURE);
          ...
.fi
.in -2

.SH ATTRIBUTES
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
.TE

.SH SEE ALSO
.BR cpr (4),
.BR attributes (7),
.BR attach (9E),
.BR detach (9E)
.sp
.LP
\fIWriting Device Drivers\fR
